TypeScript 설정: TSConfig 컴파일러 옵션 마스터하기

tsconfig.json 파일은 모든 타입스크립트 프로젝트의 핵심입니다. 이 파일은 타입스크립트 컴파일러(tsc)가 .ts 파일을 자바스크립트로 변환하는 방법을 지정합니다. 잘 구성된 tsconfig.json은 코드 품질을 유지하고, 다양한 환경 간의 호환성을 보장하며, 빌드 프로세스를 최적화하는 데 매우 중요합니다. 이 종합 가이드는 고급 tsconfig.json 옵션을 심층적으로 다루어, 타입스크립트 프로젝트를 최고의 성능과 유지보수성을 위해 미세 조정할 수 있도록 도와드립니다.

기본 사항 이해하기: TSConfig가 중요한 이유

고급 옵션을 살펴보기 전에, tsconfig.json이 왜 중요한지 요약해 보겠습니다:

• 컴파일 제어: 프로젝트에 포함될 파일과 컴파일 방법을 지정합니다.
• 타입 검사: 타입 검사의 규칙과 엄격성을 정의하여 개발 주기 초기에 오류를 발견할 수 있도록 돕습니다.
• 출력 제어: 대상 자바스크립트 버전, 모듈 시스템, 출력 디렉토리를 결정합니다.
• IDE 통합: 코드 완성, 오류 강조, 리팩토링과 같은 기능을 위해 IDE(VS Code, WebStorm 등)에 중요한 정보를 제공합니다.

tsconfig.json 파일이 없으면 타입스크립트 컴파일러는 기본 설정을 사용하는데, 이는 모든 프로젝트에 적합하지 않을 수 있습니다. 이로 인해 예기치 않은 동작, 호환성 문제, 이상적이지 않은 개발 경험이 발생할 수 있습니다.

TSConfig 생성하기: 빠른 시작

tsconfig.json 파일을 생성하려면, 프로젝트의 루트 디렉토리에서 다음 명령어를 실행하면 됩니다:

            tsc --init
            

              
                Copy
              
            
          

이 명령어는 몇 가지 일반적인 옵션이 포함된 기본 tsconfig.json 파일을 생성합니다. 그런 다음 프로젝트의 특정 요구사항에 맞게 이 파일을 사용자 정의할 수 있습니다.

주요 컴파일러 옵션: 상세 개요

tsconfig.json 파일에는 타입스크립트 컴파일러를 설정하는 compilerOptions 객체가 포함되어 있습니다. 가장 중요하고 일반적으로 사용되는 몇 가지 옵션을 살펴보겠습니다:

target

이 옵션은 컴파일된 자바스크립트 코드의 ECMAScript 대상 버전을 지정합니다. 컴파일러가 사용할 자바스크립트 기능을 결정하여 대상 환경(예: 브라우저, Node.js)과의 호환성을 보장합니다. 일반적인 값으로는 ES5, ES6(ES2015), ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext가 있습니다. ESNext를 사용하면 가장 최신의 지원되는 ECMAScript 기능을 대상으로 합니다.

예시:

            "compilerOptions": {
  "target": "ES2020"
}
            

              
                Copy
              
            
          

이 설정은 컴파일러가 ECMAScript 2020과 호환되는 자바스크립트 코드를 생성하도록 지시합니다.

module

이 옵션은 컴파일된 자바스크립트 코드에서 사용할 모듈 시스템을 지정합니다. 일반적인 값으로는 CommonJS, AMD, System, UMD, ES6(ES2015), ES2020, ESNext가 있습니다. 모듈 시스템의 선택은 대상 환경과 사용 중인 모듈 로더(예: Node.js, Webpack, Browserify)에 따라 달라집니다.

예시:

            "compilerOptions": {
  "module": "CommonJS"
}
            

              
                Copy
              
            
          

이 설정은 일반적으로 CommonJS 모듈 시스템을 사용하는 Node.js 프로젝트에 적합합니다.

lib

이 옵션은 컴파일 과정에 포함될 라이브러리 파일 집합을 지정합니다. 이 라이브러리 파일들은 내장 자바스크립트 API 및 브라우저 API에 대한 타입 정의를 제공합니다. 일반적인 값으로는 ES5, ES6, ES7, DOM, WebWorker, ScriptHost 등이 있습니다.

예시:

            "compilerOptions": {
  "lib": ["ES2020", "DOM"]
}
            

              
                Copy
              
            
          

이 설정은 ECMAScript 2020과 DOM API에 대한 타입 정의를 포함하며, 이는 브라우저 기반 프로젝트에 필수적입니다.

allowJs

이 옵션은 타입스크립트 컴파일러가 타입스크립트 파일과 함께 자바스크립트 파일을 컴파일하도록 허용합니다. 이는 자바스크립트 프로젝트를 타입스크립트로 마이그레이션하거나 기존 자바스크립트 코드베이스와 함께 작업할 때 유용할 수 있습니다.

예시:

            "compilerOptions": {
  "allowJs": true
}
            

              
                Copy
              
            
          

이 옵션을 활성화하면 컴파일러는 .ts와 .js 파일을 모두 처리합니다.

checkJs

이 옵션은 자바스크립트 파일에 대한 타입 검사를 활성화합니다. allowJs와 함께 사용하면, 타입스크립트가 자바스크립트 코드의 잠재적인 타입 오류를 식별할 수 있게 해줍니다.

예시:

            "compilerOptions": {
  "allowJs": true,
  "checkJs": true
}
            

              
                Copy
              
            
          

이 설정은 타입스크립트와 자바스크립트 파일 모두에 대해 타입 검사를 제공합니다.

jsx

이 옵션은 JSX 구문(React 및 다른 프레임워크에서 사용)이 어떻게 변환되어야 하는지를 지정합니다. 일반적인 값으로는 preserve, react, react-native, react-jsx가 있습니다. preserve는 JSX 구문을 그대로 두고, react는 React.createElement 호출로 변환하며, react-native는 React Native 개발용이고, react-jsx는 JSX 팩토리 함수로 변환합니다. react-jsxdev는 개발 목적으로 사용됩니다.

예시:

            "compilerOptions": {
  "jsx": "react"
}
            

              
                Copy
              
            
          

이 설정은 React 프로젝트에 적합하며, JSX를 React.createElement 호출로 변환합니다.

declaration

이 옵션은 타입스크립트 코드에 대한 선언 파일(.d.ts)을 생성합니다. 선언 파일은 코드에 대한 타입 정보를 제공하여 다른 타입스크립트 프로젝트나 자바스크립트 프로젝트가 적절한 타입 검사를 통해 코드를 사용할 수 있게 해줍니다.

예시:

            "compilerOptions": {
  "declaration": true
}
            

              
                Copy
              
            
          

이 설정은 컴파일된 자바스크립트 파일과 함께 .d.ts 파일을 생성합니다.

declarationMap

이 옵션은 생성된 선언 파일에 대한 소스맵 파일(.d.ts.map)을 생성합니다. 소스맵을 사용하면 디버거 및 기타 도구가 선언 파일로 작업할 때 원본 타입스크립트 소스 코드로 다시 매핑할 수 있습니다.

예시:

            "compilerOptions": {
  "declaration": true,
  "declarationMap": true
}
            

              
                Copy
              
            
          

sourceMap

이 옵션은 컴파일된 자바스크립트 코드에 대한 소스맵 파일(.js.map)을 생성합니다. 소스맵을 사용하면 브라우저나 다른 환경에서 디버깅할 때 디버거 및 기타 도구가 원본 타입스크립트 소스 코드로 다시 매핑할 수 있습니다.

예시:

            "compilerOptions": {
  "sourceMap": true
}
            

              
                Copy
              
            
          

outFile

이 옵션은 모든 출력 파일을 연결하여 단일 파일로 내보냅니다. 이는 일반적으로 브라우저 기반 애플리케이션을 위한 코드 번들링에 사용됩니다.

예시:

            "compilerOptions": {
  "outFile": "dist/bundle.js"
}
            

              
                Copy
              
            
          

outDir

이 옵션은 컴파일된 자바스크립트 파일의 출력 디렉토리를 지정합니다. 지정하지 않으면 컴파일러는 소스 파일과 동일한 디렉토리에 출력 파일을 배치합니다.

예시:

            "compilerOptions": {
  "outDir": "dist"
}
            

              
                Copy
              
            
          

이 설정은 컴파일된 자바스크립트 파일을 dist 디렉토리에 배치합니다.

rootDir

이 옵션은 타입스크립트 프로젝트의 루트 디렉토리를 지정합니다. 컴파일러는 이 디렉토리를 사용하여 모듈 이름을 해석하고 출력 파일 경로를 생성합니다. 이는 복잡한 프로젝트 구조에 특히 유용합니다.

예시:

            "compilerOptions": {
  "rootDir": "src"
}
            

              
                Copy
              
            
          

removeComments

이 옵션은 컴파일된 자바스크립트 코드에서 주석을 제거합니다. 이는 출력 파일의 크기를 줄이는 데 도움이 될 수 있습니다.

예시:

            "compilerOptions": {
  "removeComments": true
}
            

              
                Copy
              
            
          

noEmitOnError

이 옵션은 타입 오류가 감지될 경우 컴파일러가 자바스크립트 파일을 내보내는 것을 방지합니다. 이를 통해 유효한 코드만 생성되도록 보장합니다.

예시:

            "compilerOptions": {
  "noEmitOnError": true
}
            

              
                Copy
              
            
          

strict

이 옵션은 모든 엄격한 타입 검사 옵션을 활성화합니다. 잠재적인 오류를 잡아내고 모범 사례를 강제하는 데 도움이 되므로 새 프로젝트에 강력히 권장됩니다.

예시:

            "compilerOptions": {
  "strict": true
}
            

              
                Copy
              
            
          

strict 모드를 활성화하는 것은 다음 옵션들을 활성화하는 것과 같습니다:

• noImplicitAny
• noImplicitThis
• alwaysStrict
• strictNullChecks
• strictFunctionTypes
• strictBindCallApply
• noImplicitReturns
• noFallthroughCasesInSwitch

esModuleInterop

이 옵션은 CommonJS와 ES 모듈 간의 상호 운용성을 활성화합니다. 이를 통해 ES 모듈에서 CommonJS 모듈을 가져올 수 있고 그 반대도 가능합니다.

예시:

            "compilerOptions": {
  "esModuleInterop": true
}
            

              
                Copy
              
            
          

forceConsistentCasingInFileNames

이 옵션은 파일 이름의 대소문자 일관성을 강제합니다. 일부 운영 체제는 대소문자를 구분하지만 다른 운영 체제는 그렇지 않기 때문에 크로스 플랫폼 호환성에 중요합니다.

예시:

            "compilerOptions": {
  "forceConsistentCasingInFileNames": true
}
            

              
                Copy
              
            
          

baseUrl and paths

이 옵션들은 모듈 해석을 설정할 수 있게 해줍니다. baseUrl은 비상대적 모듈 이름을 해석하기 위한 기본 디렉토리를 지정하고, paths는 사용자 정의 모듈 별칭을 정의할 수 있게 해줍니다.

예시:

            "compilerOptions": {
  "baseUrl": ".",
  "paths": {
    "@components/*": ["src/components/*"],
    "@utils/*": ["src/utils/*"]
  }
}
            

              
                Copy
              
            
          

이 설정은 @components/MyComponent 및 @utils/myFunction과 같은 별칭을 사용하여 모듈을 가져올 수 있게 해줍니다.

고급 설정: 기본을 넘어서

이제, 타입스크립트 개발 경험을 더욱 향상시킬 수 있는 고급 tsconfig.json 옵션 몇 가지를 살펴보겠습니다.

증분 컴파일

타입스크립트는 증분 컴파일을 지원하여 대규모 프로젝트의 빌드 프로세스 속도를 크게 향상시킬 수 있습니다. 증분 컴파일을 활성화하려면 incremental 옵션을 true로 설정하고 tsBuildInfoFile 옵션을 지정하십시오.

예시:

            "compilerOptions": {
  "incremental": true,
  "tsBuildInfoFile": ".tsbuildinfo"
}
            

              
                Copy
              
            
          

tsBuildInfoFile 옵션은 컴파일러가 빌드 정보를 저장할 파일을 지정합니다. 이 정보는 후속 빌드 중에 다시 컴파일해야 할 파일을 결정하는 데 사용됩니다.

프로젝트 레퍼런스

프로젝트 레퍼런스는 코드를 더 작고 관리하기 쉬운 프로젝트로 구조화할 수 있게 해줍니다. 이는 대규모 코드베이스의 빌드 시간과 코드 구성을 개선할 수 있습니다. 이 개념에 대한 좋은 비유는 마이크로서비스 아키텍처입니다 - 각 서비스는 독립적이지만 생태계의 다른 서비스에 의존합니다.

프로젝트 레퍼런스를 사용하려면 각 프로젝트에 대해 별도의 tsconfig.json 파일을 만들어야 합니다. 그런 다음, 메인 tsconfig.json 파일에서 references 옵션을 사용하여 참조해야 할 프로젝트를 지정할 수 있습니다.

예시:

            {
  "compilerOptions": {
    ...
  },
  "references": [
    { "path": "./project1" },
    { "path": "./project2" }
  ]
}
            

              
                Copy
              
            
          

이 설정은 현재 프로젝트가 ./project1 및 ./project2 디렉토리에 위치한 프로젝트에 의존함을 명시합니다.

커스텀 트랜스포머

커스텀 트랜스포머를 사용하면 타입스크립트 컴파일러의 출력을 수정할 수 있습니다. 이는 사용자 정의 코드 변환 추가, 사용하지 않는 코드 제거 또는 특정 환경에 대한 출력 최적화와 같은 다양한 목적으로 사용될 수 있습니다. 일반적으로 i18n 국제화 및 현지화 작업에 사용됩니다.

커스텀 트랜스포머를 사용하려면, 컴파일러가 호출할 함수를 내보내는 별도의 자바스크립트 파일을 만들어야 합니다. 그런 다음 tsconfig.json 파일의 plugins 옵션을 사용하여 트랜스포머 파일을 지정할 수 있습니다.

예시:

            {
  "compilerOptions": {
    ...
    "plugins": [
      { "transform": "./transformer.js" }
    ]
  }
}
            

              
                Copy
              
            
          

이 설정은 ./transformer.js 파일을 커스텀 트랜스포머로 사용하도록 지정합니다.

Files, Include, Exclude

compilerOptions 외에도, tsconfig.json의 다른 최상위 옵션들은 컴파일 과정에 포함될 파일을 제어합니다:

• files: 컴파일에 포함할 파일 경로의 배열입니다.
• include: 포함할 파일을 지정하는 glob 패턴의 배열입니다.
• exclude: 제외할 파일을 지정하는 glob 패턴의 배열입니다.

이러한 옵션들은 타입스크립트 컴파일러가 처리할 파일을 세밀하게 제어할 수 있게 해줍니다. 예를 들어, 테스트 파일이나 생성된 코드를 컴파일 과정에서 제외할 수 있습니다.

예시:

            {
  "compilerOptions": { ... },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.spec.ts"]
}
            

              
                Copy
              
            
          

이 설정은 src 디렉토리와 그 하위 디렉토리의 모든 파일을 포함하면서, node_modules와 dist 디렉토리의 파일, 그리고 .spec.ts 확장자를 가진 파일(일반적으로 유닛 테스트에 사용됨)을 제외합니다.

특정 시나리오를 위한 컴파일러 옵션

프로젝트마다 최적의 결과를 얻기 위해 다른 컴파일러 설정이 필요할 수 있습니다. 몇 가지 특정 시나리오와 각 시나리오에 권장되는 컴파일러 설정을 살펴보겠습니다.

웹 애플리케이션 개발

웹 애플리케이션 개발의 경우, 일반적으로 다음과 같은 컴파일러 설정을 사용하게 됩니다:

            {
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "Node",
    "jsx": "react-jsx",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "sourceMap": true,
    "outDir": "dist"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}
            

              
                Copy
              
            
          

이 설정은 React 또는 다른 유사한 프레임워크를 사용하는 현대적인 웹 애플리케이션에 적합합니다. 최신 ECMAScript 기능을 대상으로 하고, ES 모듈을 사용하며, 엄격한 타입 검사를 활성화합니다.

Node.js 백엔드 개발

Node.js 백엔드 개발의 경우, 일반적으로 다음과 같은 컴파일러 설정을 사용하게 됩니다:

            {
  "compilerOptions": {
    "target": "ESNext",
    "module": "CommonJS",
    "esModuleInterop": true,
    "strict": true,
    "sourceMap": true,
    "outDir": "dist",
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}
            

              
                Copy
              
            
          

이 설정은 CommonJS 모듈 시스템을 사용하는 Node.js 애플리케이션에 적합합니다. 최신 ECMAScript 기능을 대상으로 하고, 엄격한 타입 검사를 활성화하며, JSON 파일을 모듈로 가져올 수 있도록 허용합니다.

라이브러리 개발

라이브러리 개발의 경우, 일반적으로 다음과 같은 컴파일러 설정을 사용하게 됩니다:

            {
  "compilerOptions": {
    "target": "ES5",
    "module": "UMD",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "**/*.spec.ts"]
}
            

              
                Copy
              
            
          

이 설정은 브라우저와 Node.js 환경 모두에서 사용할 수 있는 라이브러리를 만드는 데 적합합니다. 향상된 개발자 경험을 위해 선언 파일과 소스맵을 생성합니다.

TSConfig 관리 모범 사례

tsconfig.json 파일을 관리할 때 유념해야 할 몇 가지 모범 사례는 다음과 같습니다:

• 기본 설정으로 시작하기: 공통 설정을 담은 기본 tsconfig.json 파일을 만들고, 다른 프로젝트에서 extends 옵션을 사용하여 확장합니다.
• strict 모드 사용하기: 잠재적인 오류를 잡아내고 모범 사례를 강제하기 위해 strict 모드를 활성화합니다.
• 모듈 해석 설정하기: import 오류를 피하기 위해 모듈 해석을 적절하게 설정합니다.
• 프로젝트 레퍼런스 사용하기: 프로젝트 레퍼런스를 사용하여 코드를 더 작고 관리하기 쉬운 프로젝트로 구조화합니다.
• tsconfig.json 파일을 최신 상태로 유지하기: tsconfig.json 파일을 정기적으로 검토하고 프로젝트가 발전함에 따라 업데이트합니다.
• tsconfig.json 파일을 버전 관리하기: 다른 소스 코드와 함께 tsconfig.json 파일을 버전 관리에 커밋합니다.
• 설정 문서화하기: tsconfig.json 파일에 주석을 추가하여 각 옵션의 목적을 설명합니다.

결론: TypeScript 설정 마스터하기

tsconfig.json 파일은 타입스크립트 컴파일러를 설정하고 빌드 프로세스를 제어하는 강력한 도구입니다. 사용 가능한 옵션을 이해하고 모범 사례를 따르면, 타입스크립트 프로젝트를 최적의 성능, 유지보수성, 호환성을 위해 미세 조정할 수 있습니다. 이 가이드는 tsconfig.json 파일에서 사용 가능한 고급 옵션에 대한 포괄적인 개요를 제공하여 타입스크립트 개발 워크플로우를 완전히 제어할 수 있도록 도와드립니다. 항상 최신 정보와 지침을 얻으려면 공식 타입스크립트 문서를 참조하는 것을 잊지 마십시오. 프로젝트가 발전함에 따라, 이러한 강력한 설정 도구에 대한 이해와 활용도도 함께 성장해야 합니다. 즐거운 코딩 되세요!